 /*******************************************************************************
  * Copyright (c) 2003, 2006 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  *******************************************************************************/

 package org.eclipse.osgi.framework.adaptor;

 import java.io.IOException ;

 /**
  * Permission Storage interface for managing a persistent storage of
  * bundle permissions.
  *
  * <p>This class is used to provide methods to manage
  * persistent storage of bundle permissions. The PermissionStorage object
  * is returned by the FrameworkAdaptor object and is called
  * to persistently store bundle permissions.
  *
  * <p>The permission data will typically take the form of encoded
  * <tt>PermissionInfo</tt> Strings.
  * See org.osgi.service.permissionadmin.PermissionInfo.
  *
  * <p>For example
  * <pre>
  * PermissionStorage storage = adaptor.getPermissionStorage();
  * try {
  * storage.setPermissionData(location, permissions);
  * } catch (IOException e) {
  * // Take some error action.
  * }
  * </pre>
  * <p>
  * Clients may implement this interface.
  * </p>
  * @since 3.1
  */
 public interface PermissionStorage {
     /**
      * Returns the locations that have permission data assigned to them,
      * that is, locations for which permission data
      * exists in persistent storage.
      *
      * @return The locations that have permission data in
      * persistent storage, or <tt>null</tt> if there is no permission data
      * in persistent storage.
      * @throws IOException If a failure occurs accessing persistent storage.
      */
     public String [] getLocations() throws IOException ;

     /**
      * Gets the permission data assigned to the specified
      * location.
      *
      * @param location The location whose permission data is to
      * be returned.
      * The location can be <tt>null</tt> for the default permission data.
      *
      * @return The permission data assigned to the specified
      * location, or <tt>null</tt> if that location has not been assigned any
      * permission data.
      * @throws IOException If a failure occurs accessing persistent storage.
      */
     public String [] getPermissionData(String location) throws IOException ;

     /**
      * Assigns the specified permission data to the specified
      * location.
      *
      * @param location The location that will be assigned the
      * permissions.
      * The location can be <tt>null</tt> for the default permission data.
      * @param data The permission data to be assigned, or <tt>null</tt>
      * if the specified location is to be removed from persistent storaqe.
      * @throws IOException If a failure occurs modifying persistent storage.
      */
     public void setPermissionData(String location, String [] data) throws IOException ;

     /**
      * Persists the array of encoded ConditionalPermissionInfo strings
      * @param infos an array of encoded ConditionalPermissionInfo strings
      * @throws IOException If a failure occurs modifying persistent storage.
      * @since 3.2
      */
     public void saveConditionalPermissionInfos(String [] infos) throws IOException ;

     /**
      * Returns the persistent array of encoded ConditionalPermissionInfo strings
      * @return an array of encoded ConditionalPermissionInfo strings or null
      * if none exist in persistent storage.
      * @throws IOException If a failure occurs accessing persistent storage.
      * @since 3.2
      */
     public String [] getConditionalPermissionInfos() throws IOException ;
 }

